<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<HTML LANG="EN-US">
<HEAD>
<TITLE>VT100.net: VT330/VT340 Programmer Reference Manual</TITLE>
<LINK HREF="vt330.css" TYPE="text/css" REL="stylesheet">
</HEAD>
<BODY>
<DIV CLASS="navbar"><A HREF="http://vt100.net/"><IMG CLASS="button" SRC="vt100.net-logo.png" ALT="VT100.net" HEIGHT="16" WIDTH="102"></A> VT330/VT340 Programmer Reference Manual Volume 2: Graphics Programming<TABLE WIDTH="100%">
<COL SPAN="3" WIDTH="33%">
<TBODY>
<TR>
<TD ALIGN="LEFT"><A HREF="chapter9.html">Chapter 9</A></TD>
<TD ALIGN="CENTER"><A HREF="contents.html">Contents</A></TD>
<TD ALIGN="RIGHT"><A HREF="chapter11.html">Chapter 11</A></TD>
</TR>
</TBODY>
</TABLE>
<HR></DIV>
<H1 ID="S10"><SPAN CLASS="chapnum">10</SPAN> Report Command</H1>
<P>You can use report commands to perform two basic functions.</P>
<UL>
<LI>Request the current status of ReGIS operations.</LI>
<LI>Enter graphics input mode (to use a mouse or graphics tablet).</LI>
</UL>
<H2 ID="S10.1">Report Options</H2>
<P>Your application can request information about the following ReGIS operations.</P>
<UL>
<LI>Cursor position</LI>
<LI>Macrograph contents</LI>
<LI>Macrograph storage status</LI>
<LI>Character set</LI>
<LI>Error condition</LI>
<LI>Input mode</LI>
</UL>
<P>When your application requests information, make sure the system does not
display the information on the screen. The data could affect your graphic images.
There is no ReGIS control to prevent this action. All information returned
by the VT300 ends with a carriage return (CR).</P>
<H3 ID="S10.1.1">Cursor Position</H3>
<P>This option tells ReGIS to report the absolute screen coordinates of the current
output cursor position. The report format is as an absolute, bracketed extent in
screen coordinates. You use the following format for the report cursor position
option.</P>
<P CLASS="example">R(P)</P>
<P>where</P>
<DIV CLASS="example"><P><B>R</B> identifies a report command.</P>
<P><B>P</B> identifies the report active position option.</P></DIV>
<H3 ID="S10.1.2">Macrograph Contents</H3>
<P>This option tells ReGIS to report the contents of a specified macrograph. You
use the following format for the report macrograph contents option.</P>
<P CLASS="note">NOTE: Reporting the contents of a macrograph may be a security risk in some
environments. The VT300 has a Graphics Set-Up feature that lets the user disable
this report command option.</P>
<P CLASS="example">R(M(&lt;call letter&gt;))</P>
<P>where</P>
<DIV CLASS="example"><P><B>M</B> identifies a report macrograph option.</P>
<P><B>&lt;call letter&gt;</B> is the letter of the alphabet that identifies the requested
macrograph. The call letter is not case sensitive. For example, 'a' and 'A' identify
the same macrograph.</P></DIV>
<P>The macrograph contents report starts with a macrograph report indicator.</P>
<P CLASS="example">@=&lt;call letter&gt;</P>
<P>The <B>&lt;call letter&gt;</B> is the letter of the alphabet used to identify the requested
macrograph. The report ends with a macrograph terminator and a carriage return.</P>
<P CLASS="example">@;&lt;CR&gt;</P>
<P>The terminal also reports any control characters saved as part of the macrograph.
If there is no macrograph defined for &lt;call letter&gt;, the terminal reports
a null macrograph (no characters) enclosed in the indicator and terminator.</P>
<H3 ID="S10.1.3">Macrograph Storage Status</H3>
<P>This option tells ReGIS to report how much storage space can be used for
macrographs, and how much of that space is free. You use the following format
for the report macrograph storage option.</P>
<P CLASS="example">R(M(=))</P>
<P>where</P>
<DIV CLASS="example"><P><B>M</B> identifies a report macrograph option.</P>
<P><B>=</B> identifies the report macrograph storage suboption.</P></DIV>
<P>The terminal reports this information as two integer strings, separated by a
comma and enclosed in double quotes.</P>
<P CLASS="example">"aaaa, tttt"</P>
<P>where</P>
<DIV CLASS="example"><P><B>aaaa</B> is the amount of space still available for macrographs.</P>
<P><B>tttt</B> is the total amount of storage space that can be used for
macrographs.</P><P></P></DIV>
<P>You can find the amount of storage space in current use by subtracting the
available space from the total allocated.</P>
<P CLASS="example">Macrograph space in use = tttt - aaaa</P>
<H3 ID="S10.1.4">Character Set</H3>
<P>This option tells ReGIS to report the name of the character set currently selected
for load command operations. You use the following format for the report
character set option.</P>
<P CLASS="example">R(L)</P>
<P>where</P>
<P CLASS="example"><B>L</B> identifies the report character set option.</P>
<P>The terminal reports the name of the character set in the following format.</P>
<P CLASS="example">A'&lt;name&gt;'</P>
<P>The <B>&lt;name&gt;</B> is the name assigned to the character set by the specify name
option for the load command.</P>
<H3 ID="S10.1.5">Error Condition</H3>
<P>This option tells ReGIS to report the last error detected by the parser. You can
use the resynchronization character (;) to clear errors. You use the following
format for the report error condition option.</P>
<P CLASS="example">R(E)</P>
<P>where</P>
<P CLASS="example"><B>E</B> identifies the report error option.</P>
<P>The terminal reports the last error in the following format.</P>
<P CLASS="example">"&lt;N&gt;,&lt;M&gt;"</P>
<P>where</P>
<DIV CLASS="example"><P><B>&lt;N&gt;</B> is a decimal integer error code.</P>
<P><B>&lt;M&gt;</B> is the decimal ASCII code of the character flagged as the cause of
the error or 0, as noted for each error code. <A HREF="#T10-1">Table 10-1</A> describes the possible
error codes reported by the error condition option.</P></DIV>
<TABLE ID="T10-1" CLASS="majortable">
<CAPTION>Table 10-1 Report Command Error Codes (Error Condition Codes)</CAPTION>
<THEAD>
<TR VALIGN="BOTTOM">
<TH>Code</TH>
<TH>Condition</TH>
<TH>&lt;M&gt; Error Character</TH>
<TH>Meaning</TH>
</TR>
</THEAD>
<TBODY>
<TR VALIGN="TOP">
<TD>0</TD>
<TD>No error</TD>
<TD>Always 0</TD>
<TD>No error detected since the last resynchronization character (;).</TD>
</TR>
<TR VALIGN="TOP">
<TD>1</TD>
<TD>Ignore character</TD>
<TD>The ignored character</TD>
<TD>An unexpected character was found and ignored.</TD>
</TR>
<TR VALIGN="TOP">
<TD>2</TD>
<TD>Extra option coordinates</TD>
<TD>Always 0</TD>
<TD>The syntax S(H[X,Y][X,Y]) contained more than two coordinate pairs. The extra pairs were ignored.</TD>
</TR>
<TR VALIGN="TOP">
<TD>3</TD>
<TD>Extra coordinate values</TD>
<TD>Always 0</TD>
<TD>The syntax [X,Y] contained more than two coordinate values. The extra values were ignored.</TD>
</TR>
<TR VALIGN="TOP">
<TD>4</TD>
<TD>Alphabet out of range</TD>
<TD>Always 0</TD>
<TD>The syntax L(A&lt;0 to 3&gt;) contained a number less than 0 or greater than 3.</TD>
</TR>
<TR VALIGN="TOP">
<TD>5</TD>
<TD>Reserved</TD>
<TD>&#8211;</TD>
<TD>&#8211;</TD>
</TR>
<TR VALIGN="TOP">
<TD>6</TD>
<TD>Reserved</TD>
<TD>&#8211;</TD>
<TD>&#8211;</TD>
</TR>
<TR VALIGN="TOP">
<TD>7</TD>
<TD>Begin/start overflow</TD>
<TD>(B) or (S)</TD>
<TD>The stacking limit of 16 (B) and (S) options for position and vector commands was exceeded. Extra (B) or (S) options were ignored.</TD>
</TR>
<TR VALIGN="TOP">
<TD>8</TD>
<TD>Begin/start underflow</TD>
<TD>(E)</TD>
<TD>A position or vector command contained an (E) option without a corresponding (B) option. The (E) option was ignored.</TD>
</TR>
<TR VALIGN="TOP">
<TD>9</TD>
<TD>Text standard size error</TD>
<TD>Always 0</TD>
<TD>A text command selected a standard character size number of less than 0 or greater than 16.</TD>
</TR>
</TBODY>
</TABLE>
<H2 ID="S10.2">Graphics Input Modes &#8211; I</H2>
<P>This option lets you set ReGIS to one of two graphics input modes, one-shot or
multiple. In a graphics input mode, you can use a locator device (mouse or
graphics tablet) to move the graphics input cursor and send position reports.</P>
<H3 ID="S10.2.1">One-Shot Graphics Input Mode</H3>
<P>This is the default input mode. In one-shot mode, the terminal suspends processing
of new data from the application until ReGIS sends a position report.
The terminal buffers any data received from the application in this mode.</P>
<H4 ID="S10.2.1.1">Entering One-Shot Mode</H4>
<P>You use the input mode option to enter one-shot
mode. You use the following format for this option.</P>
<P CLASS="example">R(I0)</P>
<P>where</P>
<DIV CLASS="example"><P><B>I</B> identifies the input mode option.</P>
<P><B>0</B> identifies the input mode as one-shot.</P></DIV>
<P>After the terminal receives a one-shot mode option, the input cursor appears on
the screen.</P>
<P CLASS="note">NOTE: When the terminal receives R(I), it returns a carriage return (CR).
Applications can use the CR for synchronization.</P>
<H4 ID="S10.2.1.2">Input Cursor Movement</H4>
<P>When you use a mouse or graphics tablet, the input
cursor moves as you move the locator device. See <A HREF="chapter15.html">Chapter 15</A> for details on
using a locator device. You can also move the cursor by pressing one of the
four arrow keys.</P>
<TABLE CLASS="dpadded">
<THEAD>
<TR>
<TH>Press</TH>
<TH>To move</TH>
</TR>
</THEAD>
<TBODY>
<TR VALIGN="TOP">
<TD>arrow key</TD>
<TD>The cursor moves one pixel in the direction of the arrow &#8211; up, down, left or right.</TD>
</TR>
<TR VALIGN="TOP">
<TD>Shift-arrow key</TD>
<TD>The cursor moves 10 pixels in the direction of the arrow.</TD>
</TR>
</TBODY>
</TABLE>
<P>If you move the cursor past a screen boundary, the cursor wraps to the other
side of the screen.</P>
<H4 ID="S10.2.1.3">Requesting a Report</H4>
<P>To request a position report in one-shot mode, the
application must send a report position interactive option to the terminal. The
format of this option is as follows.</P>
<P CLASS="example">R(P(I))</P>
<P>where</P>
<P CLASS="example"><B>P(I)</B> identifies the report position interactive option.</P>
<P>After the application sends the request, it must wait for the terminal to send
the report.</P>
<H4 ID="S10.2.1.4">Sending a Report</H4>
<P>The terminal sends a position report when you press any
non-arrow key that is not dead, or a button on the locator device. After you
press the key or button, the following occurs.</P>
<UL>
<LI><P>The terminal sends the ASCII code of the key pressed to the host.</P></LI>
<LI><P>The terminal sends the current position coordinates of the input cursor
to the host. These position coordinates are absolute X and Y
values, such as [X,Y].</P></LI>
<LI><P>The input cursor disappears from the screen, and the terminal exits
one-shot mode.</P></LI>
</UL>
<P><A HREF="chapter15.html">Chapter 15</A> describes the format of the report and provides more information
on one-shot graphics input mode.</P>
<H3 ID="S10.2.2">Multiple Graphics Input Mode</H3>
<P>This mode lets you send more than one cursor position report without exiting
graphics input mode. The terminal immediately processes characters it receives
from the host, instead of buffering them as in one-shot mode.</P>
<H4 ID="S10.2.2.1">Entering Multiple Mode</H4>
<P>You use the input mode option to enter multiple
mode. You use the following format for this option.</P>
<P CLASS="example">R(I1)</P>
<P>where</P>
<DIV CLASS="example"><P><B>I</B> identifies the input mode option.</P>
<P><B>1</B> identifies the input mode as multiple.</P></DIV>
<P>When the terminal receives the multiple graphics input mode option, the input
cursor appears on the screen. Unlike one-shot mode, the terminal continues to
process received data.</P>
<H4 ID="S10.2.2.2">Input Cursor Movement</H4>
<P>When you use a mouse or graphics tablet, the cursor
moves as you move the locator device. See <A HREF="chapter15.html">Chapter 15</A> for details on using
a locator device. In multiple mode, you can also move the cursor by pressing an
arrow key.</P>
<H4 ID="S10.2.2.3">Sending a Report</H4>
<P>There are two ways to make the terminal send a position report in multiple mode.</P>
<UL>
<LI><P><STRONG>Request a report by sending R(P(I)) to the terminal.</STRONG><BR>
When the terminal receives R(P(I)) (report position interactive option)
in multiple mode, it immediately returns a position report to
the application. The terminal remains in multiple mode.</P></LI>
<LI><P><STRONG>Press a locator button.</STRONG><BR>
When you press a locator button, the terminal immediately sends
the cursor position in absolute [X,Y] coordinates. You can continue
to send reports to the application without exiting multiple mode.</P></LI>
</UL>
<P><A HREF="chapter15.html">Chapter 15</A> describes the format of a position report and provides more information
on multiple mode.</P>
<H4 ID="S10.2.2.4">Exiting Multiple Mode</H4>
<P>The terminal stays in multiple mode until the applications
sends the R(I0) option. This option makes the terminal exit multiple mode
and enter one-shot mode. See "<A HREF="#S10.2.1">One-Shot Graphics Input Mode</A> for more information.</P>
<H3 ID="S10.2.3">Report Position Interactive &#8211; P(I)</H3>
<P>This option lets an application request an input cursor position report at any
time. You only use this option when the terminal is in a graphics input mode
(one-shot or multiple). You use the following format for this option.</P>
<P CLASS="example">R(P(I))</P>
<P>where</P>
<P CLASS="example"><B>P(I)</B> identifies the report position interactive option.</P>
<P>When an application sends R(P(I)), the following occurs.</P>
<UL>
<LI><P><STRONG>In one-shot mode</STRONG><BR>
The terminal does not return an input cursor position report until
you press an active nonarrow key or a button on the locator device.
The report contains this ASCII keystroke, followed by the cursor position
in absolute [X,Y] coordinates.</P></LI>
<LI><P><STRONG>In multiple mode</STRONG><BR>
The terminal immediately returns an input cursor position report.
The report contains only the cursor position in absolute [X,Y]
coordinates.</P></LI>
</UL>
<P>See <A HREF="chapter15.html">Chapter 15</A> for information on the report format.</P>
<H2 ID="S10.3">Report Command Summary</H2>
<P><A HREF="#T10-2">Table 10-2</A> is a summary of <B>R</B> command options, including any default values.</P>
<TABLE ID="T10-2" CLASS="summarytable" FRAME="VOID" RULES="GROUPS" CELLSPACING="0" CELLPADDING="4">
<CAPTION>Table 10-2 Report Command Summary</CAPTION>
<COL WIDTH="30%">
<COL WIDTH="20%">
<COL WIDTH="50%">
<THEAD>
<TR VALIGN="BOTTOM">
<TH>Option</TH>
<TH>Default</TH>
<TH>Description</TH>
</TR>
</THEAD>
<TBODY>
<TR VALIGN="TOP">
<TD>(P)</TD>
<TD>None</TD>
<TD><P><STRONG>Cursor position</STRONG><BR>
Reports the current active position.</P></TD>
</TR>
<TR VALIGN="TOP">
<TD>(M(&lt;call letter&gt;))</TD>
<TD>None</TD>
<TD><P><STRONG>Macrograph contents</STRONG><BR>
Reports the contents of the macrograph identified by &lt;call letter&gt;.</P></TD>
</TR>
<TR VALIGN="TOP">
<TD>(M(=))</TD>
<TD>None</TD>
<TD><P><STRONG>Macrograph storage status</STRONG><BR>
Reports how much space the terminal has assigned to macrograph storage, and how much of that space is currently free.</P></TD>
</TR>
<TR VALIGN="TOP">
<TD>(L)</TD>
<TD>None</TD>
<TD><P><STRONG>Character set</STRONG><BR>
Reports which character set (1 to 3) is selected for loading.</P></TD>
</TR>
<TR VALIGN="TOP">
<TD>(E)</TD>
<TD>None</TD>
<TD><P><STRONG>Error</STRONG><BR>
Reports the last error found by the parser.</P></TD>
</TR>
<TR VALIGN="TOP">
<TD>(In)</TD>
<TD>0</TD>
<TD><P><STRONG>Graphics input mode</STRONG><BR>
Selects one-shot mode (0) or multiple mode (1).</P></TD>
</TR>
<TR VALIGN="TOP">
<TD>(P(I))</TD>
<TD>None</TD>
<TD><P><STRONG>Report position interactive</STRONG><BR>
Requests an input cursor position report.</P></TD>
</TR>
</TBODY>
</TABLE>
<DIV CLASS="navbar"><HR>
<TABLE WIDTH="100%">
<COL SPAN="3" WIDTH="33%">
<TBODY>
<TR>
<TD ALIGN="LEFT"><A HREF="chapter9.html">Chapter 9</A></TD>
<TD ALIGN="CENTER"><A HREF="contents.html">Contents</A></TD>
<TD ALIGN="RIGHT"><A HREF="chapter11.html">Chapter 11</A></TD>
</TR>
</TBODY>
</TABLE>
<DIV CLASS="navbot">http://vt100.net/docs/vt3xx-gp/chapter10.html</DIV></DIV>
</BODY>
</HTML>
